概述

本文主要介绍Retrofit 2.0的基础知识

基础

基本介绍

Retrofit是由Square开发的一个Android和Java的REST库，可以利用接口、方法和注解参数来声明式定义一个请求应该如何被创建
Retrofit背后的HTTP client、序列化机制（JSON/XML协议）都是可替换（pluggable）的，使用者可以选择适合自己的方案
请求的发送实现分同步和异步两种
支持RxJava
Retrofit 1不够好：
- 为了支持可替换的功能模块，必须嵌套大量的组件，类的数量极多
- 如果想要操作某次请求返回的数据，如返回的Header部分或URL，又同时想要操作序列化后的数据部分，这些在Retrofit 1.0上是不可能实现
- 在同步、异步和RxJava的使用上比较刻板，不够灵活，如异步和同步的调用必须得分别声明两次方法
- Retrofit 1里Converter工作的效率不高，如传入了Response和想要转换的格式Type参数后，Converter必须得搞清楚到底应该如何去反序列化，这部分的实现很复杂，而且耗时

配置

在根模块的build.gradle文件的dependencies块中添加

1	compile 'com.squareup.retrofit2:retrofit:2.0.0-beta4'

API接口

定义形式

在Retrofit 2.0中，创建Service更简单了，因为只需定义一种形式

public interface APIService {
    @POST("/list")
    Call<Repo> loadRepo();
}

Call类型

Retrofit 2.0使用新的类型Call来用于OkHttp的API请求，另外，每一个call对象实例只能被用一次，即request和response是一一对应，可以通过clone方法来创建一个一模一样的实例

同步 & 异步

Retrofit 2.0支持在同一个类型中的同步和异步，同时一个请求也可以被终止

同步
- 调用execute方法执行同步请求
- 不能在Android主线程（Main Thread）中直接使用，因为会堵塞线程，否则会报错（NetworkOnMainThreadException）
1
2
Call<Repo> call = service.loadRepo();
Repo repo = call.execute();

异步

调用enqueue方法执行异步请求
onResponse和onFailure方法会在主线程（Main Thread）中被调用

Call<Repo> call = service.loadRepo();
call.enqueue(new Callback<Repo>() {
    @Override
    public void onResponse(Response<Repo> response) {
        // Get result Repo from response.body()
    }
    @Override
    public void onFailure(Throwable t) {
    }
});

取消请求：可以随时调用cancel方法来取消请求

Response类型

Retrofit 2.0中使用了参数化的Response类型，Response对象增加了一些重要元数据：响应码（the response code）、响应消息（the response message）、响应头（headers）等
Response类型提供了一系列函数，如code用来判断请求是否成功完成，body用来获取响应体等
只有响应成功后，才会去做反序列化操作，然后将反序列化的结果放到body回调中
具体的ResponseBody（简单封装了的content-type、length、raw body等部分）由开发者处理

动态URL参数

Retrofit 2.0使用新的标注@Url来允许直接传入一个请求的URL
请求的服务器可能将header link地址列表里的数据已经缓存在服务器内存里，可以直接根据该地址去请求，然后毫不费劲地从数据库里拿数据，速度上也更快

API接口实现

Converter

Retrofit 2.0中，Converter不再包含在包里了，开发者需要自己插入一个Converter，否则Retrofit只能接收到字符串的结果
Retrofit 2.0支持多个Converter
可以自定义实现Converter.Factory接口

Converter	Dependencies
Gson	com.squareup.retrofit:converter-gson
Jackson	com.squareup.retrofit:converter-jackson
Moshi	com.squareup.retrofit:converter-moshi
Protobuf	com.squareup.retrofit:converter-protobuf
Wire	com.squareup.retrofit:converter-wire
Simple XML	com.squareup.retrofit:converter-simplexml

新的URL定义形式

Base URL：总是以/结束
@Url：不要以/开始；Retrofit 2.0中可以在@Url中定义一个完全的URL

请求方法

Retrofit的HTTP注解用来修饰请求方法

方法	描述
GET	请求指定url的数据,请求体为空(例如打开网页)。
POST	请求指定url的数据，同时传递参数(在请求体中)。
HEAD	类似于get请求，只不过返回的响应体为空，用于获取响应头。
PUT	从客户端向服务器传送的数据取代指定的文档的内容。
DELETE	请求服务器删除指定的页面。
CONNECT	HTTP/1.1协议中预留给能够将连接改为管道方式的代理服务器。
OPTIONS	允许客户端查看服务器的性能。
TRACE	回显服务器收到的请求，主要用于测试或诊断。

URL MANIPULATION

@Path：一个请求的URL可以使用方法上的替换块和参数来动态更新。一个替换块是由{和}包围，一个适合的参数必须使用同一字符串的@Path来注解
@Query：添加查询参数
@QueryMap：若有多个查询参数时，可以放在Map中

REQUEST BODY

一个对象可以使用@Body注解被用作一个HTTP请求体。该对象也会通过使用在Retrofit实例中指定的转换器来转换，如果没有提添加转换器，默认使用RequestBody

FORM ENCODED AND MULTIPART

用于方法上

@FormUrlEncoded：发送表单数据，每个键值对使用带名称和提供的值的@Field注解
@Multipart：在方法上使用@Multipart注解，对每个part使用@Part注解，其中parts可以使用Retorfit的转换器或实现RequestBody来处理序列化

HEADER MANIPULATION

使用@Headers注解来为一个方法设置静态的头部

头部不能复写，拥有同一名字的所有头部会被包含在请求中
请求头可以使用@Header注解来动态更新，如果该值为null，该头部会被忽略
需要被添加到每个请求的头部可以使用OkHttp Interceptor来指定

OkHttp

Retrofit 2.0中需要OkHttp库，并且被自动设置为依赖库
Retrofit 2.0中无论响应是否能被解析，onResponse总会被调用，万一返回的结果不能被解析为对象，response.body()会返回null，注意不要忘记处理此情况
Retrofit 2.0中如果忘记添加INTERNET权限，会立即抛出SecurityException，如果没有处理try-catch的话，会引起应用崩溃
Retrofit 2.0中需要创建一个带Interceptor的OkHttpClient，然后作为参数放入Retrofit的Builder链中

RxJava

Retrofit 2.0中除了定义Call<T>形式的接口，也可以定义自己的类型，该机制称为CallAdapter
RxJava作为一种非常流行的CallAdapter，返回的类型为Observable<T>

RxJava需要在根模块的build.gradle文件中使用如下依赖

1 2	compile 'com.squareup.retrofit:adapter-rxjava:2.0.0-beta2' compile 'io.reactivex:rxandroid:1.0.1'

在Retrofit的Builder链中作为addCallAdapterFactory的参数
API接口的方法返回对象是Observable类型
必须让代码在主线程中被调用，即observeOn(AndroidSchedulers.mainThread())方法

Retrofit 2.0使用总结

概述

基础